Subscriber Detail ================= The subscriber detail interface is used to query the billing system for more detailed information on a specific subscriber. The subscriber's unique id (which was obtained during search) is used for retrieval. The subscriber detail requires all optional fields that were available in subscriber search, plus other billing information fields. Responses are expected to be JSON. Subscriber Detail Parameters (HTTP GET) --------------------------------------- The lookup is done using HTTP GET with the following parameters: +---------------+--------------------------------------------+ |Element Name | Description | +===============+============================================+ |id |Unique id of subscriber | +---------------+--------------------------------------------+ |key |Key used for securing query pages. This is | | |same key as used in search | +---------------+--------------------------------------------+ The subscriber's unique id would have been obtained from using the Subscriber Search interface defined previously. The id could be cached from a search beforehand, so if an id does not match an error should be returned. Response JSON ------------- The JSON response is an object with the following properties: +---------------+-----------------------------------------------------------------+ | Property Name |Description | +===============+=================================================================+ | error | If there is an error this contains a short description of the | | | problem retrieving the customer info. If there was no error | | | this should be set to null | +---------------+-----------------------------------------------------------------+ | customer | A customer object. If there is no error set then this is used | | | as the result for the given customer id | +---------------+-----------------------------------------------------------------+ Customer Object _______________ all fields except company_id are required to be present (only name, or the combination of firstname and lastname should be used, however). If a value is unavailable or does not apply, then it should be set to null: +------------------------+---------+-----------------------------------------------------------------+ | Property Name | Type | Description | +========================+=========+=================================================================+ | name | string | name of subscriber. If this is used then firstname and | | | | lastname should not be included. | +------------------------+---------+-----------------------------------------------------------------+ | firstname | string | Firstname of subscriber. This this is used then name should | | | | not be included | +------------------------+---------+-----------------------------------------------------------------+ | lastname | string | Lastname of subscriber. This this is used then name should | | | | not be included | +------------------------+---------+-----------------------------------------------------------------+ | username | string | Username of subscriber in the billing web portal, if available | +------------------------+---------+-----------------------------------------------------------------+ | id | string | Unique id of subscriber. This does not have to be numeric. | +------------------------+---------+-----------------------------------------------------------------+ | status | string | Status of subscriber which must be one of the following values: | | | | * 'active' - services are all active | | | | * 'disabled' - one or more services are disabled (possibly due | | | | to non-payment) | | | | * 'cancelled' - account has been shut-off and not intended for | | | | re-activation | +------------------------+---------+-----------------------------------------------------------------+ | phone |string | Primary phone number of subscriber. The value is expected to | | | | numeric, other characters will be removed. | +------------------------+---------+-----------------------------------------------------------------+ | postalcode | string | Postal/zip code of subscriber. | +------------------------+---------+-----------------------------------------------------------------+ | email | string | Billing email address of subscriber. This is where statements | | | | and other correspondence would be sent | +------------------------+---------+-----------------------------------------------------------------+ | company_id | string | companyid of subscriber (if applicable). This field may be | | | | omitted if it is unused | +---------------+--------+---------+-----------------------------------------------------------------+ | notes | string | Non-critical customer-specific notes. This isn't generally | | | | information that needs action taken (or notes from tickets) but | | | | basic non-standard account information. | +------------------------+---------+-----------------------------------------------------------------+ | critical_notes | string | Important information about an account. This can be temporary | | | | and will be displayed prominently to the technician looking up | | | | the account. | +------------------------+---------+-----------------------------------------------------------------+ | businessname | string | If this is a business account then then this is the name of the | | | | business. This should be null otherwise. Both the businessname | | | | and name fields can be used at the same time on a business | | | | account | +------------------------+---------+-----------------------------------------------------------------+ | address | string | The billing address for the account | +------------------------+---------+-----------------------------------------------------------------+ | city | string | The city for the billing address on the account | +------------------------+---------+---------+-------------------------------------------------------+ | state | string | The state for the billing address on the account | +------------------------+---------+---------+-------------------------------------------------------+ | country | string | The country for the billing address on the account | +------------------------+---------+---------+-------------------------------------------------------+ | **Basic Billing Information** | +------------------------+---------+-----------------------------------------------------------------+ | balance | numeric | The balance on the account, 0 if none | +------------------------+---------+-----------------------------------------------------------------+ |balance_overdue | numeric | The *overdue* portion of the balance on the account. This | | | | should be the same, or less than 'balance'. If there is no | | | | amount overdue then this should be 0 | +------------------------+---------+-----------------------------------------------------------------+ |balance_minimum_due_date| date | If there is a balance amount, this is the date it is due. | | | | | +------------------------+---------+-----------------------------------------------------------------+ | security_questions | object | A list of security questions and answers, where the question is | | | | the key, and the answer is the value. | +------------------------+---------+-----------------------------------------------------------------+ | statement_type | string | This may only be one of the values: | | | | * none | | | | * email | | | | * paper | | | | * other | +------------------------+---------+-----------------------------------------------------------------+ | auto_bill_type | string | This may only be one of the values: | | | | * none | | | | * credit card | | | | * echeck | | | | * paypal | | | | * other | +------------------------+---------+-----------------------------------------------------------------+ | services | array | This is a list of `Service Object`_ | +------------------------+---------+-----------------------------------------------------------------+ | packages | array | This is a list of `Package Object`_ | +------------------------+---------+-----------------------------------------------------------------+ | other_info | array | This is a list of `OtherInfo Object`_ | +------------------------+---------+-----------------------------------------------------------------+ Service Object ______________ +------------------------+---------+-----------------------------------------------------------------+ | Property Name | Type | Description | +========================+=========+=================================================================+ | name | string | Label for the service/equipment. | +------------------------+---------+-----------------------------------------------------------------+ | type | string | This may only one of the values: | | | | * dialup | | | | * email | | | | * webhosting | | | | * fixed_wireless | | | | * hotspot | | | | * dsl | | | | * static_ip | | | | * voip | | | | * router | | | | * fiber | | | | * account_portal | | | | * mdu | | | | | | | | | +------------------------+---------+-----------------------------------------------------------------+ | fields | object | The keys required for this vary depending on the service type. | | | | refer to :ref:`service-definitions` for a reference on | | | | parameters | +------------------------+---------+-----------------------------------------------------------------+ | extra_fields | object | Fields for service related information that is not covered by | | | | the required 'fields' keys. | +------------------------+---------+-----------------------------------------------------------------+ Each service type has different required fields. These keys are requried, but if the value is unavailable it can be returned as either a blank string, or null. Required fields for each type: * dialup * username * password * dsl * line_number * username * password * ip_address * fixed_wireless * ip_address * equipment_type * mac_address * email * email_address * password * webhosting * domain * voip * line_number * hotspot * static_ip * ip * fiber * router * account_portal * mdu Package Object ______________ +-------------------------------+---------+-----------------------------------------------------------------+ | Property Name | Type | Description | +===============================+=========+=================================================================+ | name | string | Name of the package | +-------------------------------+---------+-----------------------------------------------------------------+ | period_price | numeric | The amount the subscriber pays each biling period for this | | | | package | +-------------------------------+---------+-----------------------------------------------------------------+ | period | numeric | The billing period for this package, in months | +-------------------------------+---------+-----------------------------------------------------------------+ | next_bill_date | date | When the user should next expect a bill / statement for their | | | | upcoming service | +-------------------------------+---------+-----------------------------------------------------------------+ | next_due_date | date | When the next bill / statement they recieve would be due | +-------------------------------+---------+-----------------------------------------------------------------+ | next_autobill_date | date | When the customer will be charged for the next bill / statement | | | | if autopay is enabled for the customer and this specific package| +-------------------------------+---------+-----------------------------------------------------------------+ | next_service_period_start_date| date | When the service period for the next bill starts. This is | | | | assumed to last for the duration of the period for this package | +-------------------------------+---------+-----------------------------------------------------------------+ OtherInfo Object ________________ +-------------------------------+---------+-----------------------------------------------------------------+ | Property Name | Type | Description | +===============================+=========+=================================================================+ | type | string | The type of other info. Currently the only supported type is | | | | 'billing_link' | +-------------------------------+---------+-----------------------------------------------------------------+ The OtherInfo object is to represent various types of customer data that don't fit into the service or package category. Each type has required properties if that type is used. The available types are: billing_link ^^^^^^^^^^^^ This displays a custom link for this subscriber above the package and service section +-------------------------------+---------+-----------------------------------------------------------------+ | Property Name | Type | Description | +===============================+=========+=================================================================+ | label | string | This will be used for the anchor link text and is the clickable | | | | link | +-------------------------------+---------+-----------------------------------------------------------------+ | url | string | The URL to which the link text (label) will open a new tab to | +-------------------------------+---------+-----------------------------------------------------------------+ | description | string | text displayed to the right of the link to describe what the | | | | link does | +-------------------------------+---------+-----------------------------------------------------------------+ Exmaple other_info object with a 'bililng_link' type: .. code-block:: javascript { 'type': 'billing_link', 'label':'Example Link', 'url':'http://example.net', 'description': 'Custom link for customer Joe Jones' } Example Responses _________________ Example Error Response ^^^^^^^^^^^^^^^^^^^^^^ Example query URL: http://www.example.com/subscriberinfo.cgi?id=17541 Example HTTP response body with no matching id in the external system: .. code-block:: javascript {'error': '', 'customer': null } Example Success Response - no overdue balance ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This account has no overdue balance. There is 1 package billed monthly with the statement sent out 5 days before the service period starts. This is due 5 days after the service period starts. Example query URL: http://www.example.com/subscriberinfo.cgi?id=54321 Example HTTP response body: .. code-block:: javascript {'error': '', 'customer': { 'name': 'John Johnson', 'username': 'jjohnson', 'id': 54321, 'phone': '8885551234', 'postalcode': '45678', 'email': 'myaddress@example.com', 'notes': '', 'critical_notes': '', 'businessname': '', 'address': '123 N. Main Street', 'city': 'Orem', 'state': 'UT', 'country': 'USA', 'balance': 0, 'balance_overdue': 0, 'balance_minimum_due_date': null, 'security_questions': {'City born in': 'Gotham', 'First pet\'s name': 'Roger'}, 'statement_type': 'email', 'auto_bill_type': 'credit card', 'services': [{'name': 'DSL', 'type': 'dsl', 'fields': {'line_number': '8885552345', 'equipment_type': 'Acme Modem 123'}, 'extra_fields': {'speed': '1Mbps'}}], 'packages': [{'name': 'Affordable internet', 'period_price': 39.95, 'period': 1, 'next_service_period_start_date': '2015-11-01', 'next_bill_date': '2015-10-26', 'next_due_date': '2015-11-06'}] } } Example Success Response - Balance on account ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Example query URL: http://www.example.com/subscriberinfo.cgi?id=12345 Example HTTP response body: .. code-block:: javascript {'error': '', 'customer': { 'name': 'Mike Michaelson', 'username': 'mikem', 'id': 12345, 'phone': '8885552345', 'postalcode': '56789', 'email': 'mikem@example.com', 'notes': '', 'critical_notes': '', 'businessname': '', 'address': '234 N. Main Street', 'city': 'Orem', 'state': 'UT', 'country': 'USA', 'balance': 60.00, 'balance_overdue': 30.00, 'balance_minimum_due_date': '2015-10-06', 'security_questions': {'Favorite number': '42', 'First pet\'s name': 'Frank'}, 'statement_type': 'email', 'auto_bill_type': 'credit card', 'services': [{'name': 'DSL', 'type': 'dsl', 'fields': {'line_number': '8885554444', 'equipment_type': 'Acme Modem 123'}, 'extra_fields': {'speed': '1Mbps'}}], 'packages': [{'name': 'Internet', 'period_price': 30.00, 'period': 1, 'next_service_period_start_date': '2015-11-01', 'next_bill_date': '2015-10-26', 'next_due_date': '2015-11-06'}] } }